<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<link rel="Stylesheet" type="text/css" href="doc.css" />
<title>The Validation Service</title>
</head>
<body>
<h1><a name="top">The Validation Service</a></h1>

<p>
Validation of EMF models is performed by invocation of the validation service.
The <a href="../javadoc/org/eclipse/emf/validation/service/ModelValidationService.html"><em class="CodeName">ModelValidationService</em></a>
provides
<a href="../javadoc/org/eclipse/emf/validation/service/IValidator.html"><em class="CodeName">IValidator</em></a>s
that a client may use to validate a selection of elements.  The kinds of elements that are
validated depends on the nature of the validator, as determined by the
<a href="../javadoc/org/eclipse/emf/validation/model/EvaluationMode.html"><em class="CodeName">EvaluationMode</em></a>
requested by the client.
</p>

<blockquote>
	<img src="images/service.png" alt="Validation Service API"/><br/>
	<font size="-2">[<a href="images/service.svg">as SVG</a>]</font>
</blockquote>

<h2>Validation Modes</h2>
<p>
The EMF Validation Framework provides two modes of constraint evaluation, defined by the
<a href="../javadoc/org/eclipse/emf/validation/model/EvaluationMode.html"><em class="CodeName">EvaluationMode</em></a>
enumeration: <em class="CodeName">BATCH</em> and <em class="CodeName">LIVE</em>.  The
batch mode is used for static validation of a selection of model elements, usually in
response to some user action such as selecting a <em class="UILabel">Validate</em> menu
item or performing some transformation that requires validation of the model as precondition.
</p><p>
The live mode is used to validate changes to objects in some interval that may loosely be
called a "transaction."  In fact, the EMF Model Transaction API uses the live evaluation
mode to implement validation of its transactions when they are committed.  In general, though,
it is up to a client of the validation framework to determine what are the semantics of a
"transaction" and what it means to validate the changes in it.
</p>

<h2>The Batch Validator</h2>
<p>
Upon requesting a validator for the batch mode, a client may safely cast the validator to
the <a href="../javadoc/org/eclipse/emf/validation/service/IBatchValidator.html"><em class="CodeName">IBatchValidator</em></a>
interface to configure it as necessary.  The input to batch validation is a collection of
<em class="CodeName">EObject</em>s (model elements) to be validated.  The output is an
<em class="CodeName">IStatus</em> carrying any problems reported by individual validation
constraints; this result often is a multi-status.
</p>
<pre class="Code">
List objects = myResource.getContents(); // objects to validate

// create a validator
IValidator validator = ModelValidationService.getInstance().<b>newValidator(EvaluationMode.BATCH)</b>;

// use it!
IStatus results = validator.<b>validate</b>(objects);

if (!results.isOK()) {
    ErrorDialog.openError(null, "Validation", "Validation Failed", results);
}
</pre>
<p>
When performing a batch validation operation, it may be important to evaluate any
live-mode validation constraints that may have been missed during manipulation of the
model.  For example, a model may have been imported from another application that
didn't apply the same constraints.  Simply as the batch validator to include live
constraints.  The batch validator also supports reporting progress via a progress monitor,
which the generic validator interface does not:
</p>
<pre class="Code">
// create a validator.  We know it is a batch validator because we are
// asking for batch mode
final IBatchValidator validator = (<b>IBatchValidator</b>) ModelValidationService.getInstance()
        .newValidator(EvaluationMode.BATCH);

validator.<b>setIncludeLiveConstraints</b>(true);

getWorkbench().getProgressService().run(true, true, new IRunnableWithProgress() {
    public void run(IProgressMonitor monitor) {
        List objects = myResource.getContents();
        
        IStatus results = validator.validate(objects, <b>monitor</b>);

        if (!results.isOK()) {
            ErrorDialog.openError(null, "Validation", "Validation Failed", results);
        }
    }});
</pre>

<h2>The Live Validator</h2>
<p>
Upon requesting a validator for the live mode, a client may safely cast the validator to
the <a href="../javadoc/org/eclipse/emf/validation/service/ILiveValidator.html"><em class="CodeName">IBatchValidator</em></a>
interface to configure it as necessary.  The input to live validation is a collection of
<em class="CodeName">Notification</em>s representing discrete changes to model elements
(the notifiers).  These notifications primarily determine which constraints are applied
to an element.  For efficiency, live-mode constraints should declare the changes that
trigger them, but they still validate the notifying object as a whole (to support optional
invocation in batch mode).
</p>
<pre class="Code">
List notifications = transaction.getChanges(); // changes in some hypothetical transaction scope

// create a validator
IValidator validator = ModelValidationService.getInstance().<b>newValidator(EvaluationMode.LIVE)</b>;

// use it!
IStatus results = validator.<b>validate</b>(notifications);

if (!results.isOK()) {
    ErrorDialog.openError(null, "Validation", "Validation Failed", results);
}
</pre>

<blockquote>
	<img src="images/filters.png" alt="Notification and Constraint Filters"/><br/>
	<font size="-2">[<a href="images/filters.svg">as SVG</a>]</font>
</blockquote>

<p>
The live validator also can be supplied with a
<a href="../javadoc/org/eclipse/emf/validation/util/FilteredCollection.Filter.html">filter</a>,
to weed out notifications that
should not be considered for validation.  The default filter, when none is provided by
the client, filters out notifications from objects that are not (or no longer are) attached
to a <em class="CodeName">Resource</em>.
</p>
<pre class="Code">
List notifications = transaction.getChanges(); // changes in some hypothetical transaction scope

// create a validator
ILiveValidator validator = (<b>ILiveValidator</b>) ModelValidationService.getInstance()
        .newValidator(EvaluationMode.LIVE);

// validate only changes to containment references
validator.<b>setNotificationFilter</b>(new <b>FilteredCollection.Filter</b>() {
        public boolean <b>accept</b>(Object element) {
            Object feature = ((Notification) element).getFeature();
            
            return feature instanceof EReference &amp;&amp; ((EReference) feature).isContainment();
        }
    });

IStatus results = validator.validate(notifications);

if (!results.isOK()) {
    ErrorDialog.openError(null, "Validation", "Validation Failed", results);
}
</pre>

<h2>Constraint Filtering</h2>
<p>
In either batch or live validation scenarios, a client may have a need to evaluate only
some well-defined subset of the constraints that are available.  For this, a validator
can be configured with any number of
<a href="../javadoc/org/eclipse/emf/validation/service/IConstraintFilter.html"><em class="CodeName">IConstraintFilter</em></a>s.
Only constraints that match all of the filters are validated.  There is no default filter.
For example, to check only for severe problems (e.g., to evaluate preconditions of some
model transformation):
</p>
<pre class="Code">
List objects = myResource.getContents(); // objects to validate

IValidator validator = ModelValidationService.getInstance().newValidator(EvaluationMode.BATCH);

// validate only error severity and worse
validate.<b>addConstraintFilter</b>(new <b>IConstraintFilter</b>() {
        public boolean <b>accept</b>(IConstraintDescriptor constraint, EObject target) {
            ConstraintSeverity sev = constraint.getSeverity();
            return sev.toIStatusSeverity() >= IStatus.ERROR.
        }
    });
    
IStatus results = validator.validate(objects);

if (!results.isOK()) {
    ErrorDialog.openError(null, "Validation", "Validation Failed", results);
}
</pre>


<hr/>
<p>
<a href="https://www.eclipse.org/legal/epl-2.0/">Copyright (c) 2000, 2007 IBM Corporation and others.</a>
</p>
</body>
</html>
